<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
<html>
<head>
<title>First Android application</title>
<link rel="stylesheet" href="/cfg/format.css" type="text/css">
<meta http-equiv="content-type" content="text/html; charset=utf-8">
<meta name="keywords" content="Android, programming, introduction, tutorial, 
Java, mobile development">
<meta name="description" content="In this chapter of the Android tutorial, we create
our first Android application.">
<meta name="language" content="en">
<meta name="author" content="Jan Bodnar">
<meta name="distribution" content="global">

<script type="text/javascript" src="/lib/jquery.js"></script>
<script type="text/javascript" src="/lib/common.js"></script>

</head>

<body>

<div class="container2">

<div id="wide_ad" class="ltow">
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* 160x600, August 2011 */
google_ad_slot = "2484182563";
google_ad_width = 160;
google_ad_height = 600;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<div class="content2">


<a href="/" title="Home">Home</a>&nbsp;
<a href=".." title="Home">Contents</a>


<h1>First Android application</h1>


<p>
In this chapter of the Android development tutorial we will create our first 
Android application. 
</p>

<div class="big_hor">
<script type="text/javascript"><!--
google_ad_client = "ca-pub-9706709751191532";
/* big_horizontal */
google_ad_slot = "2904953388";
google_ad_width = 728;
google_ad_height = 90;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</div>

<p>
The application will just display a message on the screen. 
</p>

<pre>
$ mkdir First
$ cd First/
</pre>

<p>
We create a First directory and make it the current working
directory.
</p>

<pre>
$ android create project --target android-17 --name First \
> --path . --activity MainActivity --package com.zetcode.first
Created directory /home/janbodnar/programming/android/First/src/com/zetcode/first
Added file ./src/com/zetcode/first/MainActivity.java
Created directory /home/janbodnar/programming/android/First/res
Created directory /home/janbodnar/programming/android/First/bin
...
</pre>

<p>
We create a new Android project with the <code>android create project</code> command.
The target option specifies the Android application framework version. The name
option determines the name of the project. The path is the location of our project 
directory. The activity is the name of our default activity. Finally, the
package is the name of the package namespace for our project.
The command creates a Java file for the main activity, several directories and
XML files. 
</p>

<pre>
$ ls 
AndroidManifest.xml  bin        libs              proguard-project.txt  res
ant.properties       build.xml  local.properties  project.properties    src
</pre>

<p>
These are the files and directories created by the <code>android create project</code> 
command. The <i>AndroidManifest.xml</i> file describes the fundamental characteristics 
of the application. The source files of the application reside in the <i>src</i> directory.
In the <i>res</i> directory, we have the application's resource files. The Android application
archive file will be created in the <i>bin</i> directory. The <i>libs</i> directory is used
to store additional libraries. The <i>ant.properties</i> and <i>build.xml</i> files
are the Ant files used to build the project. Finally, the <i>local.properties</i> and
the <i>project.properties</i> are property files of the Android project. 
</p>

<div class="codehead">AndroidManifest.xml</div>
<pre class="code">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.zetcode.first"
      android:versionCode="1"
      android:versionName="1.0"&gt;
   &lt;application android:label="@string/app_name"
                   android:icon="@drawable/ic_launcher"&gt;
       &lt;activity android:name="MainActivity"
                 android:label="@string/app_name"&gt;
           &lt;intent-filter&gt;
               &lt;action android:name="android.intent.action.MAIN" /&gt;
               &lt;category android:name="android.intent.category.LAUNCHER" /&gt;
           &lt;/intent-filter&gt;
       &lt;/activity&gt;
   &lt;/application&gt;
&lt;/manifest&gt;
</pre>

<p>
This is the project manifest file. It describes some basic characteristics of the Android project.
The file provides the package name, which is com.zetcode.com in our case. 
It contains the name of the default activity. The <i>@string/app_name</i> and <i>@drawable/ic_launcher</i>
are resource values. The string resource values are set from the strings.xml file located
in the res/values subdirectory. The image resources are located in the drawable subdirectories
of the res directory. The <i>&lt;intent-filter&gt;</i> element of the main activity declares its capabilities.
It specifies what the activity can do. The two intents specify that the activity is a main entry point of the 
application, it can be the initial activity of a task and is listed in the top-level application launcher.
</p>

<div class="codehead">strings.xml</div>
<pre class="code">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
    &lt;string name="app_name"&gt;First program&lt;/string&gt;
    &lt;string name="messsage"&gt;First Android program&lt;/string&gt;
&lt;/resources&gt;
</pre>

<p>
In the <i>strings.xml</i> file we have one element which defines the resource value
referenced from the <i>AndroidManifest.xml</i> file. The file is located in the 
res/values subdirectory. We change the value of the first element 
(from 'MainActivity' to 'First program'). The name of the application is shown in the list
of the applications in the emulator. We add the second element. It 
is referenced from the <i>main.xml</i> file. 
</p>


<div class="codehead">main.xml</div>
<pre class="code">
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    &gt;
&lt;TextView
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:text="@string/message"
    /&gt;
&lt;/LinearLayout&gt;
</pre>

<p>
This is the <i>main.xml</i> file located in the res/layout subdirectory.
It defines the layout of an Activity. The application loads the layout for an 
Activity in the <code>onCreate()</code> method. In our case we have a 
vertical linear layout with one TextView widget. 
</p>

<div class="codehead">MainActivity.java</div>
<pre class="code">
package com.zetcode.first;

import android.app.Activity;
import android.os.Bundle;

public class MainActivity extends Activity
{
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState)
    {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }
}
</pre>

<p>
This is the <i>MainActivity.java</i> source file. When the activity is first
created the <code>onCreate()</code> method is called. The method loads the activity
layout defined in the <i>main.xml</i> file. 
</p>


<h2>Building the application</h2>
 
<p>
We use the <i>ant</i> tool to build the Android application.
</p>

<pre>
$ ant debug
</pre>

<p>
We execute the <code>ant debug</code> command in the project root directory. 
There are two build targets. Debug and release. We will use the debug build
target. The release build needs some additional work with signing. 
</p>

<pre>
$ ant debug install
</pre>

<p>
It is possible to build and install the application in one step using the
<code>ant debug install</code> command.
</p>

<pre>
$ ls -1 bin
AndroidManifest.xml
AndroidManifest.xml.d
build.prop
classes
classes.dex
classes.dex.d
First.ap_
First.ap_.d
First-debug.apk
First-debug-unaligned.apk
First-debug-unaligned.apk.d
jarlist.cache
proguard.txt
res
</pre>

<p>
The final Android package is created in the bin directory. The name of our 
archive file is <i>First-debug.apk</i>. 
</p>

<h2>Running the application</h2>
 
<p>
We install the application to the emulator and start it from 
it.
</p>

<pre>
$ emulator -avd AVD2 &amp;
</pre>

<p>
The emulator is started with a specific android virtual device.
</p>

<pre>
$ adb install bin/First-debug.apk 
</pre>

<p>
The <code>adb install</code> command installs the application on the emulator.
</p>

<img src="/img/java/android/firstapp.png" alt="First program">
<div class="figure">
Figure: First program
</div>

<p>
We did not use a custom icon, so the built-in icon is used. From the applications list
we select the First program application. The application is launched.
</p>

<img src="/img/java/android/firstapp2.png" alt="First program">
<div class="figure">
Figure: The First program screen
</div>

<p>
We can see the message that we have specified in the <i>strings.xml</i> file.
</p>

<p>
This chapter was an introduction Android application development.
</p>


<div class="center"> 
<script type="text/javascript"><!--
google_ad_client = "pub-9706709751191532";
/* horizontal */
google_ad_slot = "1734478269";
google_ad_width = 468;
google_ad_height = 60;
//-->
</script> 
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js"> 
</script> 
</div>
<br> 



<div class="botNav, center">
<span class="botNavItem"><a href="/">Home</a></span> ‡ <span class="botNavItem"><a href="..">Contents</a></span> ‡ 
<span class="botNavItem"><a href="#">Top of Page</a></span>
</div>


<div class="footer">
<div class="signature">
<a href="/">ZetCode</a> last modified December 5, 2012  <span class="copyright">&copy; 2007 - 2013 Jan Bodnar</span>
</div>
</div>

</div> <!-- content -->

</div> <!-- container -->

</body>
</html>

